home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -in_the_mag- / multitasking / feature / executive_v2.10 / data / developers.lha / SysInfo / SysInfo.doc < prev   
Text File  |  1997-02-23  |  21KB  |  635 lines
  1. TABLE OF CONTENTS
  2.  
  3. SysInfo.library/--background--
  4. SysInfo.library/AddNotify
  5. SysInfo.library/FreeSysInfo
  6. SysInfo.library/GetCpuUsage
  7. SysInfo.library/GetLoadAverage
  8. SysInfo.library/GetNice
  9. SysInfo.library/GetPgrp
  10. SysInfo.library/GetPid
  11. SysInfo.library/GetPpid
  12. SysInfo.library/GetTaskCpuUsage
  13. SysInfo.library/InitSysInfo
  14. SysInfo.library/RemoveNotify
  15. SysInfo.library/SetNice
  16. SysInfo.library/--background--             SysInfo.library/--background--
  17.  
  18.    PURPOSE
  19.     SysInfo.library was developed to bring together all the different
  20.     utility programs that add some new features to Amiga task
  21.     handling, like CPU usage calculation. SysInfo.library was first
  22.     developed for Executive, but it's possible to rewrite it to
  23.     support other similar programs. It's not necessary to support
  24.     all SysInfo.library functions in all implementations.
  25.  
  26.    FEATURES
  27.     * CPU usage
  28.  
  29.       SysInfo.library provides several CPU usage indicators, e.g.
  30.       total used CPU time, CPU time used during last second,
  31.       recently used CPU time. Executive will also provide context
  32.       switch counters.
  33.  
  34.     * load averages
  35.  
  36.       Load average is the number of tasks ready or running over various
  37.       periods of time, usually 1, 5 and 15 minutes. A load average 1.0
  38.       means that there has been exactly one task running.
  39.  
  40.     * PID, PPID and PGRP
  41.  
  42.       PID is a process identifier. This is a unique number assigned for
  43.       each task in the system.
  44.  
  45.       PPID is a parent process identifier. It's the PID of the process
  46.       that has created the current process.
  47.  
  48.       PGRP is a process group. Process groups can't be implemented on
  49.       Amiga at the moment, because it's impossible to distinguish if
  50.       a task is a child-task or a totally separate task. In Executive
  51.       process groups mean processes created by a specific task. The
  52.       PGRP number is the PID of the parent task. By referring to a
  53.       specific process group, you refer to all tasks created by
  54.       the parent task.
  55.  
  56.     * nice-values
  57.  
  58.       Nice-values similar to Amiga priorities, they are used by the
  59.       scheduler when calculating priorities for different tasks.
  60.  
  61.    NOTES
  62.     If some function can't be implemented, a valid error-value
  63.     should still be returned.
  64.  
  65.     A `server' in this document means the program calculating all
  66.     this information. SysInfo.library is a standard interface to
  67.     different servers.
  68.  
  69.    AUTHOR
  70.     Petri Nordlund <petrin@megabaud.fi>
  71.  
  72.    HISTORY
  73.     V1.00  First release
  74.     V1.20  No changes, Executive server modifications required
  75.            recompilation.
  76.     V1.30  (Thanks to Bernhard Möllemann <zza@rz.uni-karlsruhe.de>)
  77.            - Better names for some structures:
  78.                sysinfo            ->    SysInfo
  79.                loadaverage        ->    SI_LoadAverage
  80.                loadaverage_fixed  ->    SI_LoadAverageFixed
  81.                SysInfo_notify     ->    SI_Notify
  82.                cpu_usage          ->    SI_CpuUsage
  83.                task_cpu_usage     ->    SI_TaskCpuUsage
  84.            - SysInfo was sometimes spelled as sysinfo or Sysinfo.
  85.              It's now always SysInfo.
  86.            - sysinfo.fd is now SysInfo_lib.fd
  87.            - Changed the compiler dependant types:
  88.                int   -> LONG
  89.                short -> WORD
  90.                long  -> LONG
  91.            - Removed LOADAVG_FLOAT.
  92.            - Replaced the `use_messages' parameter in AddNotify()
  93.              call with `flags'.
  94.            - Some internal changes to support Executive V1.30
  95.     V2.00  Notification using signals now works.
  96.  
  97. SysInfo.library/AddNotify                  SysInfo.library/AddNotify
  98.  
  99.    NAME
  100.     AddNotify - Add a notification request
  101.  
  102.    SYNOPSIS
  103.     notify = AddNotify(sysinfo,flags,safety_limit);
  104.     D0                 A0      D0    D1
  105.  
  106.     struct SI_Notify *AddNotify(struct SysInfo *, WORD, LONG);
  107.  
  108.    FUNCTION
  109.     Ask the server to notify us after it has updated its information.
  110.     After the notification, new load average, CPU usage and other
  111.     information may be requested and they'll be up-to-date. Notification
  112.     is useful if your application updates its display frequently. You
  113.     don't end up updating just before the server will calculate new
  114.     information. The notification will keep your application in sync
  115.     with the server.
  116.  
  117.     There are two ways to notify your task, by signals or messages.
  118.     Signals are very fast, but they don't queue. The safety_limit
  119.     variable can be used with messages, it's the maximum number of
  120.     notification messages that will be sent to you before you reply
  121.     to them. A good value here is about 10 - 20.
  122.  
  123.     This function returns a SI_Notify structure, which you must not
  124.     modify. If you use messages for notification, it has a pointer
  125.     to a port where the messages will arrive. Just reply to the
  126.     messages you get. There may be some internal information in
  127.     these messages that the server will use so don't modify them.
  128.     If you have ask for signals to be used for notification, there
  129.     will be a signal number in the structure. Just Wait() for that
  130.     signal.
  131.  
  132.     Before requesting notification, make sure it's implemented.
  133.     The SysInfo->notify_sig_implemented is TRUE if you can use
  134.     signals and the SysInfo->notify_msg_implemented is TRUE if
  135.     notification with messages is available.
  136.  
  137.     A notification happens once every second.
  138.  
  139.    INPUTS
  140.     SysInfo - SysInfo structure returned by InitSysInfo()
  141.     flags - See <libraries/SysInfo.h>
  142.     safety_limit - maximum number of messages sent to you
  143.  
  144.    RESULT
  145.     notify - SI_Notify structure defined in <libraries/SysInfo.h> or
  146.              NULL if there was an error
  147.  
  148.    SEE ALSO
  149.     RemoveNotify(), <libraries/SysInfo.h>
  150. SysInfo.library/FreeSysInfo                SysInfo.library/FreeSysInfo
  151.  
  152.    NAME
  153.     FreeSysInfo - Finish using the SysInfo.library
  154.  
  155.    SYNOPSIS
  156.     FreeSysInfo(SysInfo);
  157.                 A0
  158.  
  159.     void FreeSysInfo(struct SysInfo *);
  160.  
  161.    FUNCTION
  162.     Declares that you are finished using the services provided by
  163.     SysInfo.library. The SysInfo structure will be freed.
  164.  
  165.    INPUTS
  166.     SysInfo - structure returned by InitSysInfo()
  167.  
  168.    RESULT
  169.     None
  170.  
  171.    SEE ALSO
  172.     InitSysInfo(), <libraries/SysInfo.h>
  173. SysInfo.library/GetCpuUsage                SysInfo.library/GetCpuUsage
  174.  
  175.    NAME
  176.     GetCpuUsage - Get the current CPU usage values
  177.  
  178.    SYNOPSIS
  179.     GetCpuUsage(sysinfo, cpuusage);
  180.                 A0       A1
  181.  
  182.     void GetCpuUsage(struct SysInfo *, struct SI_CpuUsage *);
  183.  
  184.    FUNCTION
  185.     The SI_CpuUsage structure will be filled with current CPU usage
  186.     values.
  187.  
  188.     The SysInfo->cpu_usage_implemented field indicates what values
  189.     are implemented in the SysInfo.library. The corresponding
  190.     bits are defined in <libraries/SysInfo.h>:
  191.  
  192.     CPU_USAGEF_TOTAL_IMPLEMENTED
  193.  
  194.       Total CPU usage. The SI_CpuUsage->total_used_cputime is the
  195.       CPU time used in seconds. The SI_CpuUsage->total_elapsed_time
  196.       is the used CPU time plus idle CPU time, i.e. the elapsed time
  197.       since CPU time calculations began. You can calculate the CPU
  198.       usage percentage in this way:
  199.  
  200.           100 * total_used_cputime / total_elapsed_time
  201.  
  202.     CPU_USAGEF_LASTSEC_IMPLEMENTED
  203.  
  204.       CPU time used by all processes during last second. The
  205.       SI_CpuUsage->used_cputime_lastsec_hz is the number of clock
  206.       ticks during one second. The SI_CpuUsage->used_cputime_lastsec
  207.       is the number of ticks used. To calculate the percentage
  208.       of CPU time used:
  209.  
  210.           100 * used_cputime_lastsec / used_cputime_lastsec_hz
  211.  
  212.     CPU_USAGEF_RECENT_IMPLEMENTED
  213.  
  214.       The SI_CpuUsage->recent_used_cputime is a decaying average of
  215.       recent CPU usage. In Executive this is for the last minute.
  216.       The time in seconds is stored in SI_CpuUsage->recent_seconds.
  217.       You can calculate recent CPU usage percentage in this way:
  218.  
  219.          100 * recent_used_cputime / recent_used_cputime_hz
  220.  
  221.     CPU_USAGEF_IVVOCSW_IMPLEMENTED
  222.  
  223.       Some servers can also keep a count of the number of context
  224.       switches. A context switch happens when one task is switched
  225.       to another. The SI_CpuUsage->involuntary_csw field indicates
  226.       the total number of involuntary context switches and the
  227.       SI_CpuUsage->voluntary_csw field indicates the total number
  228.       of voluntary context switches.
  229.  
  230.       Involuntary context switch happens when the CPU is taken away
  231.       from a task that has not finished using it. This happens when
  232.       a higher priority task becomes ready to run.
  233.  
  234.       Voluntary context switch happens when task calls Wait() and
  235.       a lower priority task gets CPU time.
  236.  
  237.     CPU_USAGEF_TOTALCSW_IMPLEMENTED
  238.  
  239.       In some implementations only the total number of context
  240.       switches is available. The SI_CpuUsage->total_csw is just
  241.       involuntary context switches plus voluntary context switches,
  242.       if specific information is available.
  243.  
  244.     CPU_USAGEF_IVVOCSW_LASTSEC_IMPLEMENTED
  245.     CPU_USAGEF_TOTALCSW_LASTSEC_IMPLEMENTED
  246.  
  247.       Like above, but for the last second.
  248.  
  249.     Do all calculations with 32-bits values.
  250.  
  251.    INPUTS
  252.     sysinfo - SysInfo structure returned by InitSysInfo()
  253.     cpuusage - SI_CpuUsage structure defined in <libraries/SysInfo.h>
  254.  
  255.    RESULT
  256.     None
  257.  
  258.    SEE ALSO
  259.     GetTaskCpuUsage(), <libraries/SysInfo.h>
  260. SysInfo.library/GetLoadAverage             SysInfo.library/GetLoadAverage
  261.  
  262.    NAME
  263.     GetLoadAverage - Get load averages
  264.  
  265.    SYNOPSIS
  266.     GetLoadAverage(sysinfo, loadaverage);
  267.                    A0       A1
  268.  
  269.     void GetLoadAverage(struct SysInfo *, struct SI_LoadAverage *);
  270.  
  271.    FUNCTION
  272.     This function fills the SI_LoadAverage structure with current load
  273.     average values. There are three values which mean the average load
  274.     for the last few minutes. Usually these are 1, 5 and 15 minutes,
  275.     but this may vary. The number of seconds each load average means,
  276.     is stored in SysInfo->loadavg_time[1-3]. Value 0 means that
  277.     the load average for that time is not implemented.
  278.  
  279.     The SysInfo->loadavg_type field indicates the way the load
  280.     averages are stored in the SI_LoadAverage structure. This can
  281.     be LOADAVG_NONE, in which case load averages are not available
  282.     at all. LOADAVG_FIXEDPNT means that the load averages are stored
  283.     as 32-bit values that have been multiplied with SysInfo->fscale.
  284.     To get the actual load average, you need to calculate in floating
  285.     point numbers:
  286.  
  287.       (float) loadaverage->lavg_fixed.load1 / (float) SysInfo->fscale
  288.  
  289.    INPUTS
  290.     sysinfo - SysInfo structure returned by InitSysInfo()
  291.     loadaverage - SI_LoadAverage structure defined in <libraries/SysInfo.h>
  292.  
  293.    RESULT
  294.     None
  295.  
  296.    SEE ALSO
  297.     <libraries/SysInfo.h>
  298. SysInfo.library/GetNice                    SysInfo.library/GetNice
  299.  
  300.    NAME
  301.     GetNice - get internal priority, nice-value
  302.  
  303.    SYNOPSIS
  304.     nice = GetNice(sysinfo, which, who)
  305.     D0             A0       D0     D1
  306.  
  307.     LONG GetNice(struct SysInfo *, LONG, LONG);
  308.  
  309.    FUNCTION
  310.     Get a nice-value for a process or group of processes. Nice-value
  311.     is used when the server also contains a scheduler, like Executive.
  312.     Nice-value is used when calculating scheduling priorities for tasks.
  313.  
  314.     The nice-value that gives most CPU time is available from
  315.     SysInfo->nicemin (usually -20) and the nice-value that gives
  316.     least CPU time is in SysInfo->nicemax (usually +20).
  317.  
  318.     Which is one of PRIO_PROCESS, PRIO_PGRP, PRIO USER or PRIO_TASK and
  319.     who is interpreted relative to which (a process identifier for
  320.     PRIO_PROCESS, process group identifier for PRIO_PGRP, user ID
  321.     for PRIO_USER and a task address for PRIO_TASK). A zero value of
  322.     who denotes the current process, process group, user or task. Prio
  323.     is a value in the range SysInfo->nicemin to SysInfo->nicemax.
  324.  
  325.     The GetNice() call returns the highest nice-value (usually lowest
  326.     numerical value) enjoyed by any of the specified processes.
  327.  
  328.     Bits in SysInfo->which_implemented indicate what values you can
  329.     use for which. If this value is 0, then GetNice() and SetNice()
  330.     routines are not available.
  331.  
  332.    INPUTS
  333.     sysinfo - SysInfo structure returned by InitSysInfo()
  334.     which - get priority from which processes
  335.     who - depends on which-field, 0 means current process, PGRP, user or task
  336.  
  337.    RESULT
  338.     nice - highest nice-value enjoyed by any of the specified processes
  339.            If an error occurs, -1 is returned. Since -1 is a legitimate
  340.            value, it is necessary to look at SysInfo->errno. If errno
  341.            is zero, no error has occurred. Possible errors are:
  342.  
  343.       WHICH_ESRCH   No process was located using the which and who
  344.                     values specified.
  345.  
  346.       WHICH_EINVAL  Which was not one of PRIO_PROCESS, PRIO_PGRP,
  347.                     PRIO_USER or PRIO_TASK, or that value is not
  348.                     supported.
  349.  
  350.    NOTES
  351.     The name of this function should have been GetPriority() like in
  352.     Un*x, but then it might have been confused with Exec priorities.
  353.  
  354.    SEE ALSO
  355.     <libraries/SysInfo.h>
  356. SysInfo.library/GetPgrp                    SysInfo.library/GetPgrp
  357.  
  358.    NAME
  359.     GetPgrp - Get a process group identifier
  360.  
  361.    SYNOPSIS
  362.     pgrp = GetPgrp(sysinfo);
  363.     D0             A0      
  364.  
  365.     LONG GetPgrp(struct SysInfo *);
  366.  
  367.    FUNCTION
  368.     The process group of the current process is returned by GetPgrp().
  369.  
  370.     If this function is available, the SysInfo->GetPgrp_implemented
  371.     field is TRUE.
  372.  
  373.    INPUTS
  374.     sysinfo - SysInfo structure returned by InitSysInfo()
  375.  
  376.    RESULT
  377.     pgrp - process group identifier or -1 if process group is unknown
  378.  
  379.    SEE ALSO
  380.     GetPid(), GetPpid(), <libraries/SysInfo.h>
  381. SysInfo.library/GetPid                     SysInfo.library/GetPid
  382.  
  383.    NAME
  384.     GetPid - Get a process identifier
  385.  
  386.    SYNOPSIS
  387.     pid = GetPid(sysinfo);
  388.     D0           A0      
  389.  
  390.     LONG GetPid(struct SysInfo *);
  391.  
  392.    FUNCTION
  393.     GetPid() returns the process ID of the calling task.  The ID is
  394.     guaranteed to be unique and is useful for constructing temporary
  395.     file names.
  396.  
  397.     This routine is always available. If special unique PIDs can't
  398.     be given, it return the task address, so calling this is equivalent
  399.     to calling FindTask(NULL).
  400.  
  401.    INPUTS
  402.     sysinfo - SysInfo structure returned by InitSysInfo()
  403.  
  404.    RESULT
  405.     pid - process identifier
  406.  
  407.    SEE ALSO
  408.     GetPgrp(), GetPpid(), <libraries/SysInfo.h>
  409. SysInfo.library/GetPpid                    SysInfo.library/GetPpid
  410.  
  411.    NAME
  412.     GetPpid - Get a parent process identifier
  413.  
  414.    SYNOPSIS
  415.     pid = GetPpid(sysinfo);
  416.     D0            A0      
  417.  
  418.     LONG GetPpid(struct SysInfo *);
  419.  
  420.    FUNCTION
  421.     GetPpid() returns the process ID of the parent of the calling task.
  422.  
  423.     If this function is available, the SysInfo->GetPpid_implemented
  424.     field is TRUE.
  425.  
  426.    INPUTS
  427.     sysinfo - SysInfo structure returned by InitSysInfo()
  428.  
  429.    RESULT
  430.     pid - parent process identifier or -1 if parent is unknown
  431.  
  432.    SEE ALSO
  433.     GetPgrp(), GetPid(), <libraries/SysInfo.h>
  434. SysInfo.library/GetTaskCpuUsage            SysInfo.library/GetTaskCpuUsage
  435.  
  436.    NAME
  437.     GetCpuUsage - Get the current CPU usage values for a task
  438.  
  439.    SYNOPSIS
  440.     success = GetTaskCpuUsage(sysinfo, taskcpuusage, task);
  441.     D0                        A0       A1            A2
  442.  
  443.     LONG GetTaskCpuUsage(struct SysInfo *, struct SI_TaskCpuUsage *, struct Task *);
  444.  
  445.    FUNCTION
  446.     The cpu_usage structure will be filled with current CPU usage
  447.     values for the specified task. Specify NULL for current task.
  448.     This routine is rather similar to GetCpuUsage, but has some
  449.     small differences.
  450.  
  451.     The SysInfo->task_cpu_usage_implemented field indicates what
  452.     values are implemented in the SysInfo.library. The corresponding
  453.     bits are defined in <libraries/SysInfo.h>:
  454.  
  455.     TASK_CPU_USAGEF_TOTAL_IMPLEMENTED
  456.  
  457.       Total CPU usage. The SI_TaskCpuUsage->total_used_time_hz is the
  458.       number of clock ticks during one second. The SI_TaskCpuUsage->
  459.       total_used_cputime is the total number of ticks used. You can
  460.       calculate the CPU usage percentage in this way:
  461.  
  462.           100 * total_used_cputime / total_used_time_hz
  463.  
  464.       The SI_TaskCpuUsage->total_elapsed_time is the used CPU time plus
  465.       idle CPU time, i.e. the elapsed time since the task was created.
  466.       You can calculate how many percent of CPU time task has used:
  467.  
  468.           100 * (total_used_cputime / total_used_time_hz) / total_elapsed_time
  469.  
  470.       Please remember that this number doesn't mean the percentage
  471.       of CPU time the task has used from all used CPU time. It's
  472.       the percentage of CPU time the task has used from the total
  473.       available CPU time.
  474.  
  475.     TASK_CPU_USAGEF_LASTSEC_IMPLEMENTED
  476.  
  477.       CPU time used by this task during last second. The
  478.       SI_TaskCpuUsage->used_cputime_lastsec_hz is the number of
  479.       clock ticks during one second. The SI_TaskCpuUsage->
  480.       used_cputime_lastsec is the number of ticks used. To calculate
  481.       the percentage of CPU time used:
  482.  
  483.           100 * used_cputime_lastsec / used_cputime_lastsec_hz
  484.  
  485.     TASK_CPU_USAGEF_RECENT_IMPLEMENTED
  486.  
  487.       The SI_TaskCpuUsage->recent_used_cputime is a decaying average
  488.       of recent CPU usage. In Executive this is for the last minute.
  489.       The time in seconds is stored in SI_TaskCpuUsage->recent_seconds.
  490.       You can calculate recent CPU usage percentage in this way:
  491.  
  492.          100 * recent_used_cputime / recent_used_cputime_hz
  493.  
  494.     TASK_CPU_USAGEF_IVVOCSW_IMPLEMENTED
  495.  
  496.       Some servers can also keep a count of the number of context
  497.       switches. A context switch happens when one task is switched
  498.       to another. The SI_TaskCpuUsage->involuntary_csw field indicates
  499.       the total number of involuntary context switches for the specified
  500.       task and the SI_TaskCpuUsage->voluntary_csw field indicates the
  501.       total numnber of voluntary context switches.
  502.  
  503.       Involuntary context switch happens when the CPU is taken away
  504.       from a task that has not finished using it. This happens when
  505.       a higher priority task becomes ready to run.
  506.  
  507.       Voluntary context switch happens when task calls Wait() and
  508.       a lower priority task gets CPU time.
  509.  
  510.     TASK_CPU_USAGEF_TOTALCSW_IMPLEMENTED
  511.  
  512.       In some implementations only the total number of context switches
  513.       is available. The SI_TaskCpuUsage->total_csw is just involuntary
  514.       context switches plus voluntary context switches, if specific
  515.       information is available.
  516.  
  517.     TASK_CPU_USAGEF_IVVOCSW_LASTSEC_IMPLEMENTED
  518.     TASK_CPU_USAGEF_TOTALCSW_LASTSEC_IMPLEMENTED
  519.  
  520.       Like above, but for the last second.
  521.  
  522.     Do all calculations with 32-bits values.
  523.  
  524.    INPUTS
  525.     sysinfo - SysInfo structure returned by InitSysInfo()
  526.     taskcpuusage - SI_TaskCpuUsage structure defined in
  527.                    <libraries/SysInfo.h>
  528.     task - task address, NULL for current task
  529.  
  530.    RESULT
  531.     success - 0 for success, 1 for error
  532.  
  533.    SEE ALSO
  534.     GetCpuUsage(), <libraries/SysInfo.h>
  535. SysInfo.library/InitSysInfo                SysInfo.library/InitSysInfo
  536.  
  537.    NAME
  538.     InitSysInfo - Initialize the SysInfo.library
  539.  
  540.    SYNOPSIS
  541.     SysInfo InitSysInfo(void);
  542.     D0
  543.  
  544.     struct SysInfo *InitSysInfo(void);
  545.  
  546.    FUNCTION
  547.     This function will initialize the SysInfo.library and possibly
  548.     make a connection to the server task. It returns a SysInfo structure
  549.     which you need when requesting information. The structure is read-
  550.     only and it's size may grow in later versions of the library.
  551.  
  552.    INPUTS
  553.     None
  554.  
  555.    RESULT
  556.     SysInfo - structure defined in <libraries/SysInfo.h>
  557.  
  558.    SEE ALSO
  559.     FreeSysInfo(), <libraries/SysInfo.h>
  560. SysInfo.library/RemoveNotify               SysInfo.library/RemoveNotify
  561.  
  562.    NAME
  563.     RemoveNotify - Remove a notification request
  564.  
  565.    SYNOPSIS
  566.     RemoveNotify(sysInfo,notify);
  567.                  A0      A0
  568.  
  569.     void RemoveNotify(struct SysInfo *, struct SI_Notify *);
  570.  
  571.    FUNCTION
  572.     Remove the notification request added with AddNotify(). This
  573.     function will internally make sure that you won't get any more
  574.     notification messages and it will clean up the queued messages
  575.     if any. It will also clear the signal if it was allocated.
  576.  
  577.    INPUTS
  578.     sysinfo - SysInfo structure returned by InitSysInfo()
  579.     notify - SI_Notify structure you got from AddNotify()
  580.  
  581.    RESULT
  582.     None
  583.  
  584.    SEE ALSO
  585.     AddNotify(), <libraries/SysInfo.h>
  586. SysInfo.library/SetNice                    SysInfo.library/SetNice
  587.  
  588.    NAME
  589.     SetNice - set internal priority, nice-value
  590.  
  591.    SYNOPSIS
  592.     success = SetNice(sysinfo, which, who, nice)
  593.     D0                A0       D0     D1   D2
  594.  
  595.     LONG SetNice(struct SysInfo *, LONG, LONG, LONG);
  596.  
  597.    FUNCTION
  598.     Set a nice-value for a process or group of processes. 
  599.  
  600.     See GetNice() for more information.
  601.  
  602.    INPUTS
  603.     sysinfo - SysInfo structure returned by InitSysInfo()
  604.     which - which processes are affected
  605.     who - depends on which-field, 0 means current process, PGRP,
  606.           user or task
  607.     nice - change nice to this value
  608.  
  609.    RESULT
  610.     success - 0 if there is no error, or -1 if there is, in which case
  611.               the error is in SysInfo->errno:
  612.  
  613.       WHICH_ESRCH   No process was located using the which and who
  614.             values specified.
  615.  
  616.       WHICH_EINVAL  Which was not one of PRIO_PROCESS, PRIO_PGRP,
  617.                     PRIO_USER or PRIO_TASK, or that value is not
  618.             supported.
  619.  
  620.       Some implementations may returns one of these:
  621.  
  622.       WHICH_EPERM   A process was located, but neither its effective
  623.             nor real user ID matched the effective user ID of
  624.             the caller.
  625.  
  626.       WHICH_EACCES  A non super-user attempted to lower a process
  627.             priority.
  628.  
  629.    NOTES
  630.     The name of this function should have been SetPriority() like in
  631.     Un*x, but then it might have been confused with Exec priorities.
  632.  
  633.    SEE ALSO
  634.     <libraries/SysInfo.h>
  635.